
package com.studiofortress.sf.graphics.display;

import com.studiofortress.sf.util.collections.ObjectStack;
import javax.media.opengl.GL;
import javax.media.opengl.GLCanvas;

/**
 * A GraphicsDisplay is an object that wraps a Canvas. It allows being placed as
 * the screen of a WorldContainer, offers a Controls object and a canvas which
 * can be drawn too.
 *
 * @author Joseph Lenton
 */
public interface GraphicsDisplay
{
    /**
     * An enum for the types of control events you can enable and disable from
     * this graphics display.
     */
    public static enum ControlEventType
    {
        MOTION,
        CLICK,
        KEY;
    }

    /**
     * @return The internal GLCanvas that getGL will be drawing too.
     */
    public abstract GLCanvas getCanvas();
    
    /**
     * For retireving the Control object for this window.
     * This object allows you to detect any interaction
     * between the user and the window.
     * @return The control device for this window.
     */
    public abstract Controls getControls();

    /**
     * Returns the OpenGL graphics device for the window.
     */
    public abstract GL getGL();

    /**
     * @return the height of the graphics area of the window.
     */
    public abstract int getHeight();

    /**
     * @return the width of the graphics area of the window.
     */
    public abstract int getWidth();

    /**
     * Makes the mouse pointer invisible, hiding it.
     */
    public abstract void hideMouse();

    /**
     * Tells you if the Graphics Window
     * is still running or not.
     * A window is not running if it has been closed.
     * @return True if the window is still running, false if not.
     */
    public abstract boolean isRunning();

    /**
     * Will repaint the component, displaying anything that has been drawn to
     * it. Typically this will be called at the end of all drawing.
     */
    public abstract void paint();

    /**
     * Makes the mouse pointer visible.
     */
    public abstract void showMouse();

    /**
     * Turns on control event handling for the ControlTypes given.
     * @param types The types of controls to turn on.
     */
    public abstract void enableControls( ControlEventType ... types );

    /**
     * Turns off the control handling for the control types given.
     * @param types The types of control events to turn off.
     */
    public abstract void disableControls( ControlEventType ... types );

    /**
     * Places all control events that are ready to be used into the stack
     * provided.
     *
     * This is to allow you to re-use stacks and avoid the memory overhead of
     * creating lots of lists.
     *
     * WARNING! This will not do anything unless you turn control events on in
     * this display.
     *
     * @param events A stack that can store the events.
     */
    public abstract void updateControls( ObjectStack<ControlEvent> events );
}
